affinityScoresByConfig API
Description
The affinityScoresByConfig API returns affinity scores for a shopper based on the specified affinity configuration. The API evaluates the shopper’s behavior and generates scores for configured dimensions such as brands, categories, or product attributes. These scores help determine the shopper’s level of interest in each dimension.
https://recs.richrelevance.com/rrserver/api/rrPlatform/affinityScoresByConfigParameters
Note: All parameters are case sensitive.
IMPORTANT: Only call parameters that you need. Algonomy operates off a set of APIs that support many applications and clients concurrently. Algonomy may update and enhance these APIs at any time.
|
Name |
Required or Optional |
Description |
|---|---|---|
|
affinityConfigName |
Optional |
The affinity configuration to use. If omitted, the system uses the default configuration. |
|
apiClientKey |
Required |
A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by Algonomy. Example: apiClientKey=b0126f995ac848159d |
|
apiKey |
Required |
A unique key that identifies the site. Each Algonomy client has a unique API key to separate data and traffic from other clients. This is provided by Algonomy. Example: apiKey=4faeaf752ee40a0f |
|
rcs |
Optional |
Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response. Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers. Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API. |
|
sessionId |
Optional |
Identifies a single visit by a shopper. Sessions are used by behavioral models (to scope user behavior in a shopping session) and reporting metrics. Example: sessionId=93484 |
|
userId |
Optional |
User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to Algonomy in other applications. Example: userId=0982347 If no userID is given, recommendations are based on view and purchase history (via the recentlyViewed and recentlyPurchased parameters or cookies) as well as unpersonalized strategies such as CategoryBestSellers. |
Sample Request
http://recs.richrelevance.com/rrserver/api/rrPlatform/affinityScoresByConfig?Sample Response
{
"brandScores": {
"viewScores": [
{ "affinity": "Aquazzura", "score": 1.9 }
],
"purchaseScores": [],
"cartScores": [
{ "affinity": "Marni", "score": 2.85 },
{ "affinity": "Aquazzura", "score": 2.85 }
],
"wishlistScores": [],
"categoryViewScores": [],
"combinedScores": [
{ "affinity": "Marni", "score": 2.85 },
{ "affinity": "Aquazzura", "score": 4.75 }
]
},
"categoryScores": {
"viewScores": [
{ "affinity": { "externalId": "77", "name": "Sandals" }, "score": 1.82 },
{ "affinity": { "externalId": "74", "name": "Shoes" }, "score": 1.82 },
{ "affinity": { "externalId": "10", "name": "Womens" }, "score": 1.82 }
],
"purchaseScores": [],
"cartScores": [
{ "affinity": { "externalId": "76", "name": "Pumps" }, "score": 2.73 },
{ "affinity": { "externalId": "65", "name": "Jewellery" }, "score": 2.73 },
{ "affinity": { "externalId": "74", "name": "Shoes" }, "score": 2.73 },
{ "affinity": { "externalId": "10", "name": "Womens" }, "score": 5.46 },
{ "affinity": { "externalId": "67", "name": "Necklaces" }, "score": 2.73 }
],
"wishlistScores": [],
"categoryViewScores": [],
"combinedScores": [
{ "affinity": { "externalId": "76", "name": "Pumps" }, "score": 2.73 },
{ "affinity": { "externalId": "77", "name": "Sandals" }, "score": 1.82 },
{ "affinity": { "externalId": "65", "name": "Jewellery" }, "score": 2.73 },
{ "affinity": { "externalId": "74", "name": "Shoes" }, "score": 4.55 },
{ "affinity": { "externalId": "10", "name": "Womens" }, "score": 7.28 },
{ "affinity": { "externalId": "67", "name": "Necklaces" }, "score": 2.73 }
]
},
"attributeScores": {
"viewScores": [
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "black~black" },
"score": 0.95
},
{
"affinity": { "attributeName": "size", "attributeValue": "7~8~9~10~11" },
"score": 0.28
},
{
"affinity": { "attributeName": "size", "attributeValue": "10~11~12~13~14" },
"score": 0.28
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "brown~cognac" },
"score": 0.95
}
],
"purchaseScores": [],
"cartScores": [
{
"affinity": { "attributeName": "size", "attributeValue": "5~6~7~8~9" },
"score": 0.84
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~blacksilver" },
"score": 2.85
},
{
"affinity": { "attributeName": "size", "attributeValue": "10~11~12~13~14" },
"score": 0.84
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~green~00w01lilywhite" },
"score": 2.85
}
],
"wishlistScores": [],
"categoryViewScores": [],
"combinedScores": [
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "black~black" },
"score": 0.95
},
{
"affinity": { "attributeName": "size", "attributeValue": "5~6~7~8~9" },
"score": 0.84
},
{
"affinity": { "attributeName": "size", "attributeValue": "7~8~9~10~11" },
"score": 0.28
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~blacksilver" },
"score": 2.85
},
{
"affinity": { "attributeName": "size", "attributeValue": "10~11~12~13~14" },
"score": 1.12
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "brown~cognac" },
"score": 0.95
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~green~00w01lilywhite" },
"score": 2.85
}
]
}
}
Field Descriptions
|
Field |
Description |
|---|---|
|
brandScores |
Contains affinity scores related to brands. Includes view, purchase, cart, wishlist, category-view, and combined scores. |
|
categoryScores |
Contains affinity scores related to categories. Includes view, purchase, cart, wishlist, category-view, and combined scores. |
|
attributeScores |
Contains affinity scores related to product attributes such as color, size, or other configured attribute types. |
|
viewScores |
Affinity scores calculated from products that the shopper viewed. |
|
purchaseScores |
Affinity scores calculated from products purchased by the shopper. |
|
cartScores |
Affinity scores calculated from products added to the cart. |
|
wishlistScores |
Affinity scores calculated from products added to the wishlist or favorites. |
|
categoryViewScores |
Category-level affinity scores based on viewing behavior. |
|
combinedScores |
Aggregated affinity values across all behaviors. Represents the highest-confidence affinity score per dimension. |
| affinity.externalId | The external ID of the category, as defined in the merchant catalog. |
| affinity.name | The category name. |
| attributeName | The name of the attribute (for example, ColorCode, size). |
| attributeValue | The attribute value. Multiple values are separated by the ~ delimiter. |
| score | The affinity score assigned to the brand, category, or attribute. Higher scores indicate stronger preference. |
Throttling of API Requests
Affinity Scores API requests will process up to a maximum of 1000 requests per minute. Ensure that your application throttles requests accordingly.